Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@studio-freight/lenis

Package Overview
Dependencies
Maintainers
5
Versions
111
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@studio-freight/lenis

Lenis is a smooth scroll library to normalize and smooth the scrolling experience across devices

  • 1.0.42
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
25K
increased by3.94%
Maintainers
5
Weekly downloads
 
Created
Source

LENIS

npm downloads size

Introduction

This is our take on smooth scroll, lightweight, hard-working, smooth as butter scroll. See Demo.


Installation

JavaScript

using a package manager:

npm i @studio-freight/lenis
import Lenis from '@studio-freight/lenis'

using scripts:

<script src="https://unpkg.com/@studio-freight/lenis@1.0.42/dist/lenis.min.js"></script> 

Setup

Basic:

const lenis = new Lenis()

lenis.on('scroll', (e) => {
  console.log(e)
})

function raf(time) {
  lenis.raf(time)
  requestAnimationFrame(raf)
}

requestAnimationFrame(raf)

GSAP ScrollTrigger:

const lenis = new Lenis()

lenis.on('scroll', (e) => {
  console.log(e)
})

lenis.on('scroll', ScrollTrigger.update)

gsap.ticker.add((time)=>{
  lenis.raf(time * 1000)
})

gsap.ticker.lagSmoothing(0)

React:

See documentation for react-lenis.


Instance settings

OptionTypeDefaultDescription
wrapperHTMLElement, WindowwindowThe element that will be used as the scroll container
contentHTMLElementdocument.documentElementThe element that contains the content that will be scrolled, usually wrapper's direct child
eventsTargetHTMLElement, WindowwrapperThe element that will listen to wheel and touch events
lerpnumber0.1Linear interpolation (lerp) intensity (between 0 and 1)
durationnumber1.2The duration of scroll animation (in seconds). Useless if lerp defined
easingfunction(t) => Math.min(1, 1.001 - Math.pow(2, -10 * t))The easing function to use for the scroll animation, our default is custom but you can pick one from Easings.net. Useless if lerp defined
orientationstringverticalThe orientation of the scrolling. Can be vertical or horizontal
gestureOrientationstringverticalThe orientation of the gestures. Can be vertical, horizontal or both
smoothWheelbooleantrueWhether or not to enable smooth scrolling for mouse wheel events
syncTouchbooleanfalseMimic touch device scroll while allowing scroll sync (can be unstable on iOS<16)
syncTouchLerpnumber0.075Lerp applied during syncTouch inertia
touchInertiaMultipliernumber35Manage the the strength of syncTouch inertia
wheelMultipliernumber1The multiplier to use for mouse wheel events
touchMultipliernumber1The multiplier to use for touch events
normalizeWheelbooleanfalseNormalize wheel inputs across browsers (not reliable atm)
infinitebooleanfalseEnable infinite scrolling! (See example)
autoResizebooleantrueResize instance automatically based on ResizeObserver. If false you must resize manually using .resize()

Instance Props

PropertyTypeDescription
animatedScrollnumberCurrent scroll value
dimensionsobjectDimensions instance
directionnumber1: scrolling up, -1: scrolling down
emitterobjectEmitter instance
optionsobjectInstance options
targetScrollnumberTarget scroll value
timenumberTime elapsed since instance creation
actualScrollnumberCurrent scroll value registered by the browser
velocitynumberCurrent scroll velocity
isHorizontal (getter)booleanWhether or not the instance is horizontal
isScrolling (getter)booleanWhether or not the scroll is being animated
isSmooth (getter)booleanWhether or not the scroll is animated
isStopped (getter)booleanWhether or not the user should be able to scroll
limit (getter)numberMaximum scroll value
progress (getter)numberScroll progress from 0 to 1
rootElement (getter)HTMLElementElement on which Lenis is instanced
scroll (getter)numberCurrent scroll value (handles infinite scroll if activated)
className (getter)stringrootElement className

Instance Methods

MethodDescriptionArguments
raf(time)Must be called every frame for internal usage.time: in ms
scrollTo(target, options)Scroll to target.target: goal to reach
  • number: value to scroll in pixels
  • string: CSS selector or keyword (top, left, start, bottom, right, end)
  • HTMLElement: DOM element
options
  • offset(number): equivalent to scroll-padding-top
  • lerp(number): animation lerp intensity
  • duration(number): animation duration (in seconds)
  • easing(function): animation easing
  • immediate(boolean): ignore duration, easing and lerp
  • lock(boolean): whether or not to prevent the user from scrolling until the target is reached
  • force(boolean): reach target even if instance is stopped
  • onComplete(function): called when the target is reached
on(id, function)id can be any of the following instance events to listen.
stop()Pauses the scroll
start()Resumes the scroll
resize()Compute internal sizes, it has to be used if autoResize option is false.
destroy()Destroys the instance and removes all events.

Instance Events

EventCallback Arguments
scrollLenis instance

html.lenis, html.lenis body {
  height: auto;
}

.lenis.lenis-smooth {
  scroll-behavior: auto !important;
}

.lenis.lenis-smooth [data-lenis-prevent] {
  overscroll-behavior: contain;
}

.lenis.lenis-stopped {
  overflow: hidden;
}

.lenis.lenis-scrolling iframe {
  pointer-events: none;
}

Considerations

Nested scroll

<div data-lenis-prevent>scroll content</div>

<div data-lenis-prevent-wheel>scroll content</div>

<div data-lenis-prevent-touch>scroll content</div>

See modal example

<a href="#anchor" onclick="lenis.scrollTo('#anchor')">scroll to anchor</a>

Limitations

  • no support for CSS scroll-snap
  • capped to 60fps on Safari (source) and 30fps on low power mode
  • smooth scroll will stop working over iframe since they don't forward wheel events
  • position fixed seems to lag on MacOS Safari pre-M1 (source)

Tutorials


Plugins


Lenis in use


Authors

This set of hooks is curated and maintained by the darkroom.engineering team:


License

The MIT License.

FAQs

Package last updated on 17 Mar 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc